Creating and maintaining consistent documents with elucidative development

Software systems are usually not defined in one big, all-encompassing model, but they consist of a multitude of different views from multiple technological spaces, such as requirements, class diagrams, or source code. These views contain redundancy, i.e., they share some of their information. If redundant information in different views contradicts with each other, the views become inconsistent. Inconsistency is a source of errors, and much effort is spent on research and tool development to avoid it. Documents are also views on a software system. They are usually written by human authors. In practise, documents and other views often change at different paces. Document updates are frequently omitted because they are expensive and do not pay off immediately. Consequently, documents are often outdated. Outdated documents communicate wrong information about the software. The severity of outdated information can range from a minor inconvenience for the reader to complete uselessness. Sometimes documents are generated. If generated documents are outdated, they can easily be regenerated. However, in many cases it is not possible to generate the desired document content. In this thesis, we introduce Elucidative Development (ED), an approach to create documents from other views by partial generation. Partial generation means, that some document content is generated, and the remaining document content is added manually, afterwards. Unlike naive generation approaches, ED retains manually written content when the generated content is regenerated. A guidance system informs the author about changes in the generated content and helps him update the manually written content. In an evaluation we present our findings regarding the applicability and versatility of ED. First, we analyse two model specifications, one of them being the Unified Modeling Language (UML) specification, for inconsistencies and show that the use of ED would have prevented these inconsistencies. We also show how ED helps with the update of the specifications. Then, we present several examples where we successfully wrote documents using ED.